Inside Macintosh: QuickDraw GX Objects /

Chapter 2 - Shape Objects / Shape Objects Reference

Functions / Directly Manipulating a Shape's Geometry

GXGetShapeStructure

You can use the GXGetShapeStructure function to get a pointer to the geometry of a shape object.

void *GXGetShapeStructure(gxShape source, long *length);

source

A reference to the shape object whose geometry you need access to.

length

A pointer to a long value. On return, the value specifies the size in bytes of the shape's geometry.

function result

A pointer to the geometry of the source shape object.

DESCRIPTION

The GXGetShapeStructure function determines the size of a shape's geometry and returns a pointer to the geometry in the QuickDraw GX heap. You can use the pointer to examine or change the geometry without copying the geometry into your application's heap and back again.

Before calling GXGetShapeStructure, you should first call GXLockShape to prevent the geometry from being relocated and you should set the gxDirectShape attribute to make the shape accessible in the QuickDraw GX heap. After you are finished examining or changing the geometry, call GXUnlockShape. If you change the shape's geometry, you must call the GXChangedShape function to notify QuickDraw GX that the shape's cache is no longer valid.

To edit a geometry, you need to know its structure. GXGetShapeStructure returns a pointer and a size only; it does not provide you with any information about the internal structure of the geometry. For example, if the source shape is a path, you must cast the function result to a gxPaths pointer. Such information is not described in this book.

If you call this function for a shape that has no geometry (shape types gxEmptyType and gxFullType), the function posts a graphic_type_has_no_structure warning.

SPECIAL CONSIDERATIONS

If you do not set the gxDirectShape attribute or do not lock the shape, QuickDraw GX does them for you as a side effect of the GXGetShapeStructure function call. You must still call GXUnlockShape to unlock the shape and, if you wish, reset the attribute.

This function is rarely needed. In most instances, you can manipulate a shape's geometry with calls to geometry-specific functions such as GXGetRectangle or GXGetGlyphTangents. This function is provided as a fast alternative to those functions, but be aware that it may fail in low-memory conditions; see "Special Considerations" under the description of the GXLockShape function, on page 2-80.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
graphic_type_does_not_have_a_structure	(debugging version)
Notices (debugging version)
lockShape_called_as_side_effect

SEE ALSO

The GXLockShape and GXUnlockShape functions are described in the previous sections. The GXChangedShape function is described in the following section.

Shape types are described in the section "Shape Type" beginning on page 2-9.

Shape geometry structures, and the functions for manipulating them, are described in the shape-specific chapters of Inside Macintosh: QuickDraw GX Graphics and Inside Macintosh: QuickDraw GX Typography.